home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 130_01 / ry.doc < prev    next >
Encoding:
Text File  |  1985-03-11  |  6.4 KB  |  199 lines
  1. /********************************************************************
  2.     ry.doc, doc on this stuff:
  3.  
  4.     1: random file functions, flavor ry.
  5.     2: binary file index functions, built upon random functs.
  6.     3: xswapin() and xswapout(), enhanced 'swapin()' function.
  7.  
  8. */
  9.  
  10. /*
  11.  
  12.     some notes on these functions-
  13.  
  14.  
  15.     this code has its roots in the 'rx' random file stuff.
  16. this version differs primarily in that the file is now addressed
  17. via long integers instead of the clumsy sector and byte within sector
  18. scheme of rx.  this is done with the long.c code from cug vol functions I.
  19. the binary file search code is also contained in this file now. to
  20. use this code u will need the following:
  21.  
  22.         1. ry.doc (this file)
  23.         2. ry.c
  24.         3. long.c
  25.         4. longcode.crl (asm code in longcode.mac)
  26.             (note, u presently need z-80 to use long int code)
  27.  
  28.     random file routines:
  29.  
  30.     since the buffer is completely written to disk even though only
  31. one byte may have been added, a program that uses the entire 8 megabyte
  32. range could fill a disk with 240 byes (assuming a declared buffer size
  33. of 1 k and even distribution of those bytes over the entire range). one
  34. solution would be to keep the buffer size down to 1 sector. the best is
  35. to be reasonable with the address range of your program. logically a file
  36. of 8 megabytes could be spread over x disks if necessary.
  37.  
  38.     these functions need:    1.cp/m 2.x
  39.                 2.alloc() installed in the stdlib
  40.                 3:_allocp = NULL; in main
  41.                 4.the undocumented (but existing)
  42.                     functions rsrec()
  43.                           rcfsiz()
  44.                           rtell()
  45.                           rseek()
  46.                           rread()
  47.                           rwrite()
  48.                   the code for these is in deff2a.asm
  49.                   and is the only existing doc for them
  50.  
  51.     the buffer size is declared on opening the file and is maintained
  52. in a space provided by alloc(). it can be any length from 1 sector to
  53. memory size available (keep in mind the above note on buffer size as affected
  54. by random writes). if your needs change you can close and reopen with a diff-
  55. erent size buffer. closes AUTOMATICALLY flush the buffer, no explicit call
  56. of _rflush() needed.
  57.  
  58.     see pages 164-169 of 'the c programming language' for insight
  59. into the madness of the package
  60.  
  61.     important:
  62.  
  63.     DO NOT  'rclose()' a file that is not open, rclose() will
  64. attempt to 'free()' memory that hasn't been set aside by alloc(),
  65. causing havoc to the running program!
  66.  
  67. */
  68.  
  69.  
  70. /*
  71.     routines to parallel the buffered input and output routines,
  72. allowing completely random buffered read and writes to a file
  73.  
  74.     these are closely modeled on the routines by Leor for
  75. buffered sequential files.
  76.  
  77. functions - 
  78.  
  79.     rcreat(filename, mode, secs)
  80.         creat an as yet non-existant file, returns file pointer
  81.     ropen(filename, mode, secs)
  82.         open an already existing file, returns file pointer
  83.     rclose(fp)
  84.         close a random file (takes care of all 'flushing')
  85.     _rflush(fp)
  86.         'flush' a random file buffer to disk
  87.     fseek(fp, offset, origin)
  88.         set the 'byte-pointer' to a specific byte within the
  89.             8 megabyte range of 2.2
  90.     ftell(fp)
  91.         report the current position of the 'byte-pointer' in
  92.             an open file
  93.     bseek(fp, block, origin)
  94.         does a fseek() using logical block size defined
  95.             by _blksiz in struct _file
  96.     btell(fp)
  97.         returns the last block sought by bseek()
  98.     rgetc(fp)
  99.         returns the byte pointed at by the 'byte-pointer'
  100.             and bumps the pointer by 1
  101.     rputc(c, fp)
  102.         puts the byte 'c' in the file at the position defined
  103.             by the 'byte-pointer', bumps the pointer by 1
  104.  
  105.     the next four are basically their sequential file cousins
  106. with rgetc() replacing getc() and rputc() replacing putc() in the
  107. code.
  108.  
  109.     rgetw(fp)
  110.     rputw(w, fp)
  111.     rprintf(fp, format, arg1, arg2,...)
  112.     rscanf(fp, format, arg1, arg2,...)
  113.  
  114.     rgets() and rputs() handle null terminated strings from and
  115. to files without any 'crlf' conversions. rgetl() and rputl() are the
  116. extensions of fgets() and fputs() in the distribution package. again,
  117. their code is mostly from their cousins, with changes made as
  118. necessary. the change to 'l' is to denote the fact that they work
  119. in the 'line' enviroment of cp/m.
  120.  
  121.     rgets(str, fp)
  122.     rputs(str, fp)
  123.     rgetl(line, fp)
  124.     rputl(line, fp)
  125.  
  126.     the next four are essentially two pairs of twins. they get or
  127. put x amount of bytes from/to files.
  128.  
  129.     rget(fp, destination, nbyt)
  130.     rput(fp, source, nbyt)
  131.     rgetstruct(fp, destination, structsiz)
  132.     rputstruct(fp, source, structsiz)
  133. */
  134.  
  135.  
  136. /*
  137.     binary search functions:
  138.  
  139.  
  140.     the basic structure is that of 2 files, the first is a block
  141.     of int pointers that is written into allocated core and manip-
  142.     ulated as an array, while the second is a collection of arbitrary
  143.     data that is opened in a random fashion, via the ordered pointers
  144.     of the first array.  the pointer array must fit entirely in core
  145.     limiting the # of entries to about 8000, depending on your memory
  146.     capacity.  this # is declared to bsmake, and handled for you from
  147.     there.
  148.  
  149. functions:
  150.  
  151.     bsmake(data_file, ptr_file, data_size, max_data)
  152.         make data file and pointer file, init, etc.
  153.     bsopen(data_file, ptr_file, key_comp, secs)
  154.         open data_file, allocate and load ptr_file, return bsp.
  155.     bsclose(bsp)
  156.         close the data and pointer files.
  157.     bsread(bsp, key, address)
  158.         read a block into address from file pointed at by bsp.
  159.         if the key is found, the block is read, if not, it returns
  160.         'BELONGS', no block is read.
  161.     bswrite(bsp, key, address)
  162.         write a block from address into file pointed at by bsp.
  163.         if the key is found the block is overwritten. if not found
  164.         a block is allocated in the file, it is written, and ptr is
  165.         added to the pointer file.
  166.     bssearch(bsp, key)
  167.         seeks a block headed by string 'key'. if found the random file
  168.         ptr for the datafile is made to point at the block and 'FOUND'
  169.         is returned.  if not found it returns 'BELONGS', with no action
  170.         taken on the random file ptr. the point within the pointer 
  171.         array that would contain its pointer is placed into the 
  172.         pointer array's first element ([0]). (get the point?)
  173.     bskey_add(bsp)
  174.         add key to pointer list, call bsblk_add to add block.
  175.     bsblk_add(bsp)
  176.         get block from freelist (or EOF if empty).
  177.     bskey_rmv(bsp, key)
  178.         remove key from pointer list, call bsblk_rmv to remove block.
  179.     bsblk_rmv(bsp)
  180.         add block to free list in datafile.
  181.  
  182. */
  183.  
  184. /*
  185.  
  186. any ideas, requests, bug reports etc. to:
  187.  
  188.     Steve Passe
  189.     New Ideas
  190.     P.O. Box 629
  191.     Englewood, CO    80151
  192.  
  193.     computers:    (303) 781-4937
  194.  
  195.     people:        (303) 761-4378
  196.  
  197. */
  198. 
  199.         if the key is fo